CUBE CONNECT Edition Help

Control Statements

This section describes the control statements available in the CUBE Voyager Pilot program.

  • *command - Perform an OS system command with OS window minimized

  • BREAK - Break out of current loop

  • CLEARERROR - Clear a run error to allow continued processing

  • COMP - Compute variables

  • CONTINUE - Continue to end of loop

  • CONVERTMAT - Convert Matrix files

  • COPY … ENDCOPY - Copy records to a file

  • DOWNLOAD - Download specified file(s) from a URL

  • EXIT - Exit current phase

  • FILEI - Specify input file with existing variable values

  • FILEO - Specify output file PRINTO[#]=fname

  • GOTO - Jump to a specific control statement

  • IF … ELSEIF … ELSE … ENDIF - Standard IF block

  • LOOP … ENDLOOP - Setup a user loop

  • NEWPAGE - Control new-page processing

  • ONRUNERRORGOTO - Jump to a specified :label when an error condition is encountered

  • PARAMETERS - Specify basic parameter values

  • PRINT - Print variable values

  • PROMPT - Pause execution and wait for user input

  • REPORT - Turn reports on/off

  • RUN … ENDRUN - Runs a specified program

  • SENDMAIL - Send mail with attachments based on conditions of the run

  • SLEEP - Pause program execution for specified amount of time

*command

A statement whose first field begins with a *, and is more than 2 characters long, is considered as a command for the operating system. CUBE Voyager will invoke the COMSPEC processor to execute the command. The command will return a code that will be stored in the ReturnCode variable. It is the user’s responsibility to test ReturnCode, since CUBE Voyager does not know the meaning of the return codes. It should be noted that some system commands return 0, even if they are unsuccessful. For example: “COPY source dest” will return a 0, even if one of the filenames is illegitimate.

Note: The *command will be executed in a minimized command window. This prevents disruption of the display, allowing other tasks to be performed more comfortably while the script is running. If it is required that the command window appear on the display, use the alternate **command rather than *command; for example, ‘**pause’ rather than ‘*pause’. The ‘**’ approach will be appropriate if the command requires some interaction with the user, or perhaps if it displays some progress which the user always wants to be able to view.

Example 

*DELABCD*.TMP
*IFEXISTOLD.NETDELOLD.NET

Or: 

**DELABCD*.TMP
**IFEXISTOLD.NETDELOLD.NET

BREAK

BREAK can be used to break out of a LOOP ENDLOOP block. It must be within a LOOP block. When BREAK is encountered, flow immediately branches to the statement following the appropriate ENDLOOP statement. The contents of the LOOP variable are not altered.

Example 

LOOPi=1,3
IF(condition)
statements
ELSE
BREAK;get out of loop
ENDIF
ENDLOOP

CLEARERROR

Keywords include:

The CLEARERROR statement is used primarily in conjunction with the variable ONRUNERRORGOTO. When the statement is encountered, it automatically resets the internal error code value to 1 and the resume switch to false. It is then the user’s responsibility to set those values with the keywords.

CLEARERROR keywords:

  • CODE - |I| - Internal error code is reset to this value. Can be a value of 0,1.

  • RESUME - |?| - If the value is True (1), and the program detects that it is in an error recovery process set by ONRUNERRORGOTO, control will switch to the statement following the RUN statement that caused control to switch to the recovery process.

Example 

ONRUNERRORGOTO = 'MYERROR'
:STEP1
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR
 
:STEP2
RUN PGM=….
ENDRUN
 
:STEP3
RUN PGM=
ENDRUN
 
:MYERROR
PRINT LIST='Special Message'
CLEARERROR CODE=0 RESUME=T
; At this point, control will return to :Step2

COMP

var=expression

ID=expression

Lambda=expression

etc…

COMP statements compute numeric values and store the value into the var on the left side of the equals sign. Results can be either numeric or character strings (obtained when literal text ‘…’ or text functions are in the expression). It is not permissible to change the mode of a variable during an application. A variable must be defined before it can be used within an expression; it must have appeared as a var= in a statement prior to the expression. The program is designed with this check, to ensure that an edit can be made prior to beginning processing. It could be a big waste of time, if, in the middle of a complicated loop, the program had to abort because it couldn’t find a variable at that time. However, this causes a problem with using variables returned from a CUBE Voyager program invoked by the RUN PGM= statement. CUBE Voyager does not know the mode of the variable and can not edit it prior to actual application. To avoid this problem, CUBE Voyager automatically assumes any variable that contains a dot (".") within its name as numeric.

  • Var is the variable that is to have a new value computed for it. If the variable matches a name in the Vars array, the result will be updated after the COMP is completed. If it does not exist in the Vars array, it is added as a new variable that can be referenced in subsequent control statements.

  • ID is a special case variable that allows the user to compute a new ID. Because of the potential conflict with the CUBE Voyager system ID control statement, ID may not be the first keyword on a COMP statement. If the result of the expression is not numeric, then the resulting character string is copied to the system ID area. In any event, ID then becomes a working variable.

  • Lambda is a special case variable, and Lambda must also be a variable within the expression. When this form is specified, the program solves the expression for various values of Lambda between 0 and 1.0 in hopes of determining a Lambda that will result in a value of 0. The logic for searching is as follows:

    • Set a min and max Lambda (0 and 1.0)

    • Divide the difference between min and max into equal intervals.

    • Solve for all the interval points between min and max.

    • Find the interval that surrounds 0; if none do, it is an error. If more than one interval surrounds 0, the solution is ambiguous, and it is an error.

    • Reset the min and max Lambdas to the interval points that contain 0.

    • If the interval size is not within the accepted tolerance, repeat steps 2-5.

    • When the interval size is within tolerance, perform a straight line interpolation to zero. Store the results into Lambda.

    This is not a perfect solution, but if the expression is appropriate (does not contain any transverse slopes, and crosses zero one time), a Lambda between 0 and 1 will be found. The current process works on a bisecting principal for developing the test ranges and uses an tolerance interval of 0.000001. For obvious reasons, an expression that contains Lambda as an expression multiplier without any other terms, will always result in Lambda = 0. A division by Lambda will cause program failure when Lambda is tested for 0.

The statement need not have COMP, it may begin directly with var=.

Example 

COMP i=matrix.time_to_cbd/100 + sqrt(loop)
i=3, j=6, k=9, ijk=1*100+j*10 + k
Lambda = 1.2 - lambda * ... 
COMP ID='This is a new ID for loop' + str(loop_cntr,3,0)

CONTINUE

Jumps to the end of a loop, bypassing all intermediate statements.

When CONTINUE is processed flow immediately branches to the ENDLOOP statement in a LOOP ENDLOOP block. It must be within a LOOP block.

Example 

LOOP i=1,3
IF (condition)
statements
ELSE
CONTINUE  ; jump to ENDLOOP
ENDIF
ENDLOOP

CONVERTMAT

Command for converting matrix files between the CUBE native ‘TPP’ format and the open matrix format ‘OMX’. More information on the open matrix format can be found at https://github.com/osPlanning/omx

Keywords include:

  • FROM - |F| - Name of the file that contains the matrix that needs to be converted.

  • TO - |F| - Name of the file that contains the converted matrix.

  • TO>COMPRESSION - |I| - Level of compression to be applied for the output file. Valid values are 0 to 9. Higher the value, higher the rate of compression and slower conversion speeds. Default is 0.A good compression/speed balance seems to be 4.

  • TO>FORMAT - |S| - Format of the output matrix file. Can be either ‘TPP’ or ‘OMX’. Default is ‘OMX’

Example 

CONVERTMATFROM="C:\CUBEtown\Base\PERSONTRIPS.MAT"TO="C:\CUBEtown\Base\persontrips.omx"FORMAT=OMX COMPRESSION=0

COPY … ENDCOPY

Keywords include:

Copies records from the input file to a specified file.

All the records following the COPY statement, up to, but not including, its matching ENDCOPY statement are copied. The copied records and the ENDCOPY are not processed by CUBE Voyager. If there is no matching ENDCOPY, the end of file is considered as the ENDCOPY. The actual COPY takes place when the COPY statement is processed (it can be bypassed or repeated). If there are any COPY or ENDCOPY statements between this COPY statement and its ENDCOPY, they are copied as a data records to the designated file. The copy process does not scan the records for special features (/…/ %…% etc.).

If there is no filename, or the filename is invalid, the error is not diagnosed until the COPY statement is actually processed. For that reason, it may be better to place most COPY statements near the beginning of the input file. The primary use of COPY is to allow the user to include small data files within the input file, so that they can be always be associated directly with the control statements.

If the COPY fails, ReturnCode is set to 255; an IF statement can be used to test the results.

COPY and ENDCOPY keywords:

  • FILE - |F| - Name of the file onto which the records are to be copied. Must be an acceptable name for the operating system.

Example 

COPY FILE=temp1; copy lookup file for HIGHWAY
.
.
ENDCOPY
COPY   FILE=temp2   ;copy with imbedded COPY
  ...                will be copied to temp2
COPY   FILE=temp3   ; "   "    "    "    " 
  ...                 "   "    "    "    " 
ENDCOPY               "   "    "    "    "
ENDCOPY signals that the prior record was last
IF (ReturnCode==255) ...

DOWNLOAD

Keywords include:

Downloads a file from the internet from the specified URL.

  • CLEARFILEO - |?| - <1> is a switch to indicate if the local file should be cleared prior to beginning the download.

    If the file is cleared and the download fails for some reason then the file will not exist on the local machine. If CLEARFILEO=0 then the local file will be overwritten by a successful download but if the download fails then the original local file will remain in its original form.

  • FILEO - |S| - Local path and file name for the download.

    Example: 'C:\CITIDOWNLOADS\myfile.dat'

  • URL - |S| - URL for the target file to download.

    Example: URL= ftp://www.Bentley.com/outgoing/yourfile.dat

    The site address component (ftp://www.Bentley.com) is not case sensitive but the path and filename component is (/outgoing/yourfile.dat).

EXIT

Terminates the program.

Example 

IF(expression)EXIT

FILEI

Keywords include:

Specifies an input file for Pilot variable initialization. This statement is executed before any step is run, no matter where it is specified in the script.

Note: See FILEI for general information about FILEI and for important limitations when using Application Editor.

FILEI keywords

  • VARI - |KF| - Specifies the name of the file which is to be read to initialize variables. If not specified, no file is read. The data extracted from the file are stored in the Vars array. If duplicate variables are encountered, the latest one read prevails. Each record from the file contains two fields: a variable name, and its value. The fields may be separated by any number of space(s), with, or without, an = sign. The names may be any reasonable variable names.

The statement need not contain the FILEI control word; it may begin directly with VARI. Normally, VARI is not used; it is used only if there are many variables to be initialized. This could be the case if the application is the continuation of a previous application. A var output file will always be written at the termination of the application.

Example 

VARI=XXXX.VAR

FILEO

Keywords include:

Specifies an output file for the PRINT PRINTO capability when printing from Pilot.

FILEO keyword

  • PRINTO - |KF| - Specifies the name of the file where the output from the PRINT statement is to be directed

The statement need not contain the FILEO control word; it may begin directly with PRINTO. Note, all PRINTO index numbers must be unique throughout the script. When adding a Pilot box in Application Editor and linking a file to the PRINTO file box, you must ensure that the index numbers used do not overlap with prior PRINTO indices from prior Pilot steps.

Note: When processing the first step, the Pilot program opens all the PRINTO files specified in any script. Therefore, statements intended to create files in folders that do not already exist will fail.

Example 

FILEO PRINTO[1] = "C:\Data\My File.CSV"
IF (L1=1) 
PRINT CSV=T LIST='ITER','DIFF','P_DIFF',
        PRINTO=1
ELSE
PRINT CSV=T, FORM=L, LIST=L1,CONV.DIFF(8.0L),CONV.P_DIFF(6.2L),
        PRINTO=1
ENDIF
IF (ABS(CONV.P_DIFF)<0.05 & L1>1) BREAK
*COPY Trips_by_Mode.mat LAST.MAT/Y

GOTO

Jumps immediately to a named statement.

GOTO label

When GOTO is processed, flow immediately branches to the target statement, named :label. Each GOTO statement must have an associated :label statement. Use care when the :label statement is within a different IF or LOOP block. The target statement must begin with a semicolon (:).

Example 1 

GOTOhwybuild
GOTO:hwybuild

Example 2 

GOTOhwybuild
:hwybuild
IF(expression)GOTO:hwybuild ; It is permissible to go backwards.

IF … ELSEIF … ELSE … ENDIF

Performs certain operations based on conditions.

There are two forms of this control statement:

  • A single statement: 

    IF (expression) statement

  • A block of statements: 

    IF(expression)
ELSEIF(expression)
ELSE(expression)
ENDIF

You must predefine any expression variables in an earlier COMP VAR statement. (The program automatically defines any variables not predefined, but with a dot (.) in their name as numeric variables.)

You may nest but not overlap IF … ELSEIF … ELSE … ENDIF blocks. They may not overlap LOOP … ENDLOOP blocks.

You may append the following control statements to a single IF statement:

Example 

; Single IF examples:
 
IF (matrix.time_to_bcd < 200000) simple statement 
IF (expression) EXIT
 
; Typical IF block:
 
IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) )
statements
ELSEIF (loop_cntr > 10)
statements
ELSEIF (loop_cntr > 5 && diff.time < 32) 
statements
ELSE
statements
ENDIF

LOOP … ENDLOOP

Initializes a variable, compares the variable to a constant, and branches to the statement following the LOOP block if the comparison fails.

LOOP blocks may be nested, but they may not overlap other LOOP blocks or IF blocks. 

LOOP Var = Begin, End, Incr
Statementset
ENDLOOP

where:

  • Var is the required user-specified name of the loop-control variable. The module does not protect the value of Var during the loop; computation, program, and other LOOP statements may alter the value of Var.

  • Begin is the constant value to which the module initializes Var. You must specify a value.

  • End is the constant value that the module compares Var to when processing the ENDLOOP statement. You must specify a value.

  • Incr is the constant the module adds to Var before processing the ENDLOOP statement.

    If the result of the comparison is true, the program branches back to the statement following the LOOP statement. If it is false, control is passed to the statement following ENDLOOP.

Processing of the ENDLOOP statement depends on the value of Incr:

  • If Incr is positive, when the value of Var is less than or equal to End, the module goes to the statement following LOOP, otherwise the module goes to the statement following ENDLOOP.

  • If Incr is negative, when the value of Var is greater than or equal to End, the module goes to the statement following LOOP otherwise the module goes to the statement following ENDLOOP.

The module tests the ENDLOOP condition (without incrementing the variable value) when initializing the loop-control variable. If the test fails, the module does not perform any statements within the LOOP block.

Example 1

Executes the code within the LOOP block 10 times. 

LOOP iter=1,10 
    .
    .
ENDLOOP

Example 2

A nested loop, with the innermost loop executing twice for each value of variable xyz: 10,8,6,4,2. 

LOOP xyz=10,1,-2 
  LOOP abc=1,2 
    .
    .
  ENDLOOP
ENDLOOP

NEWPAGE

Controls the printed output when the program invokes an external process.

Keywords include:

All NEWPAGE variables are Boolean items that require a true or false type of value. Once a variable is set, it remains in force, until a new value is encountered. The …sys variables can help provide cleaner output when a system command is performed. The page counter will not be adjusted for the system output. The …sys variables are ignored if the system command contains a redirection ">" symbol.

NEWPAGE keywords

  • afterpgm - |?| - Starts a new page after a PGM returns.

  • aftersys - |?| - Starts a new page after a system command.

  • beforepgm - |?| - Sets the line counter so that the invoked PGM will start on a new page.

  • beforesys - |?| - Starts a new page before performing the system command.

Example 

NEWPAGE beforepgm=y afterpgm=n beforesys=y aftersys=y

ONRUNERRORGOTO

ONRUNERRORGOTO is a string variable that can be set to point to a legitimate label statement in the script. Use this feature to react to fatal returns from Bentley’ programs. When a "RUN PGM=program" statement is executed, the program sets a return code that indicates what type of message the program returned on closing.

The codes returned are:

  • 0 = No messages - The job ran to completion successfully.

  • 1 = Warning messages - The job ran to completion but generated one or more warning messages.

  • 2 = Fatal messages - The job failed to run to completion and generated on or more fatal error messages.

  • 3 = Program aborted - The job was aborted by user conditions with the ABORT statement.

This code value is stored in a variable named RETURNCODE.

If the RETURNCODE value is greater than 1, the run is automatically terminated. However, if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate LABEL statement in the script, the run will continue at the labeled statement if the return code is 2. See GOTO for a description of defining a LABEL.

At the labeled statement, the user can provide additional statements to further control what is to happen with the run. Typically, the user will set up a PRINT statement to write a message to the run print file or use a PROMPT statement to issue a message, and possibly request a response from the user to continue the run. The user may now also send an e-mail or text message to report results based on a run error. See SENDMAIL for an example of using these statements together.

To continue the run, the user will have to clear the internal RETURNCODE variable, or subsequent tests of the run status may cause termination. The CLEARERROR statement is used to reset the internal return code; it can not be cleared by setting RETURNCODE=. The CLEARERROR statement also provides a keyword to allow the user to resume executing script at the point following the RUN statement that caused control to be switched to the label specified by ONRUNERRORGOTO.

It is suggested that the script statements to be processed on the return of an error message be placed at the end of the run script and "jumped" to with the ONRUNERRORGOTO Statement. Note that an EXIT statement should be used just prior to the :label referenced by the ONRUNERRORGOTO. Placing an EXIT statement prior to the :label will allow the program to terminate without executing the statements for the error condition when the script runs successfully without any errors. Refer also to the CLEARERROR statement (see CLEARERROR).

Example 1 

RUNPGM=MATRIX
ENDRUN

At this point the job will terminate because there was an error in the Matrix program (no operations).

Example 2 

ONRUNERRORGOTO = 'MYERROR'
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR if the MATRIX step fails
RUN PGM=….
ENDRUN
EXIT ; if program gets to this point then exit, no errors were encountered
:MYERROR
PRINT LIST='Special Message'
; Run will terminate from here with a final completion code of 2

Example 3 

ONRUNERRORGOTO = 'MYERROR
:STEP1
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR if the MATRIX step fails
:STEP2
RUN PGM=….
ENDRUN
:STEP3
RUN PGM=
ENDRUN
EXIT ; if program gets to this point then exit, no errors were encountered
; or all errors cleared
:MYERROR
PRINT LIST='Special Message'
CLEARERROR CODE=0 
GOTO STEP3

Example 4 

ONRUNERRORGOTO = 'MYERROR'
:STEP1
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR if the MATRIX step fails
:STEP2
RUN PGM=….
ENDRUN
:STEP3
RUN PGM=
ENDRUN
EXIT ; if program gets to this point then exit, no errors were encountered
; or all errors cleared
:MYERROR
PRINT LIST='Special Message'
CLEARERROR CODE=0 RESUME=T
; At this point, control will return to :Step2

PARAMETERS

Specifies basic parameter values for the Pilot run.

Keywords include:

<…> is the program default value.

PARAMETERS keywords

  • MAXSTRING - |K| - Specifies the maximum length to use for all string variables. Versions 3.0, and lower, had a maximum length of 127 characters, and violations of this length were not detected. This proved to be too short for some users who were developing strings with considerably longer path names in them. Now the user can specify what the longest string variable is to be (up to 1000 characters). If one has many string variables, a large value could cause excessive RAM to be allocated. (We have seen users’ jobs with more than 200 string variables.) Specifying a reasonable length will help to preserve RAM, and if a string really needs to be longer than 250, this parameter must be specified. If a variable is computed to exceed this length, a fatal error message will be issued.

    Default value is 255. Maximum is 1000.

  • VARDECIMAL - |I| - Specifies the decimal place precision for numeric variables passed between Pilot and individual program modules, using the LOG statement and @…@ tokens (Statement tokens (%…% and @…@)). This will allow the user to increase the precision of the passed values as needed.

    If the parameter is specified multiple times, the value from the last occurrence will be used. This value also controls the decimal precision of variable values logged in each program module so that small values can be passed back to Pilot.

    Default is 5. Minimum is 0, maximum 15.

PRINT

Formats and prints a line of information.

The standard CUBE Voyager PRINT statement can be used. Please see PRINT.

Example 1 

LIST= ITER(6) TIMEPERIOD(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001
PRINT FORM=6.0CDLR LIST= ITER, TIMEPERIOD,TOTAL1,TOTAL2 FILE=PRINTFIL.002

Example 2 

PRINT PRINTO=1 FORM=6.0CDLR LIST=ITER, TIMEPERIOD, TOTAL1, TOTAL2

PROMPT

Keywords include:

Poses mid-run questions that can alter the flow of the job. When encountering a PROMPT statement, the program lists a question (defined by the QUESTION keyword) and the possible answers (defined by the ANSWER keyword) and waits for a response. The response must select one of the answers. The program will not continue until a proper selection is made. The ANSWER number is returned to Pilot in the variable named ReturnCode, which the user can test via an IF statement.

The use of the keyword PRNFILE on the RUN statement allows the user to redirect the print file for any job steps. When the PROMPT dialog box opens, the user can peruse the output from any of the previous step(s) to decide how to respond to the question.

PROMPT keywords

  • ANSWER - |S5| - Possible answers. The same rules about quotes in QUESTION also apply here. There may be up to 5 ANSWERs.

  • QUESTION - |KS| - Question to prompt the user with. Enclose with quotes ‘…’ or "…"; if it contains any delimiters, it must be within quotes.

  • WAIT - |R| - Number of seconds to wait before automatically continuing using ANSWER [1] as the response. If the user makes a choice before WAIT seconds have expired, the program will not continue until a valid choice is made. 0< WAIT < 50000

    When running in command line mode, as soon as a valid number is entered, the program continues with that selection without requiring a press of the Enter key. To gain more response time in command mode, enter an invalid key; the program will then wait until a valid number is entered, and WAIT is disabled.

    When in windows mode, a dialogue box is opened, and the user can make a choice and then click on the OK button to proceed. Once any choice is made, WAIT is disabled.

When Pilot is launched a Windows dialog box opens, and the user responds by selecting a button.

Example 

PROMPT  QUESTION=’What do you want to do?’,
        ANSWER=Continue,              ; 1
               ‘Break out of Loop’,   ; 2
               ABORT                  ; 3
IF (ReturnCode==3) abort
IF (ReturnCode==2) break
RUN PGM=MATRIX  PRNFILE=myfile.txt
.
.
ENDRUN
PROMPT QUESTION=’Examine myfile.txt to determine response to’, 
       ANSWER=’Sum Too High’,
              ‘Sum Too Low’,
              ‘Sum Acceptable – Get Out of Loop’
IF (RETURNCODE==3) break

REPORT

Keywords include:

REPORT keywords

  • STACK - |?| - Writes the internal stack. This is mostly used for program debugging, but can be useful for relating TRACE information to internal notation. STACK is static; if set to true, writes occur at the beginning of stack processing.

  • TRACE - |K?| - Controls the listing of the stack statements as they are processed. TRACE can be turned on and off at any time, thus controlling the amount of output as desired. Each statement will be listed with an internal number, the control statement name, and, in most cases, additional information. TRACE is a trigger key.

  • VARS - |?| - When set to true, the program lists the current variables and their values from the VARS array.

Example 

REPORT Vars=y
REPORT  Trace=y ; turn stack tracing on
REPORT Trace=n ; turn stack tracing off

RUN … ENDRUN

Loads and executes a program. Keywords include:

Pilot loads and executes the program specified by PGM. Pilot attaches any control statements between the RUN and ENDRUN command to the specified program. Only the specified program will read and edit these statements.

ENDRUN signals the end of the RUN statement. Though optional, Bentley recommends always using ENDRUN. A system command (*….) or another RUN statement also signals the end of a RUN statement.

You can disable a RUN statement by changing it to !RUN. However, a !RUN statement requires a corresponding ENDRUN. You can also disable a RUN statement by placing the statement in a null block (/* …. */) or by using a GOTO statement.

RUN keywords

  • CTLFILE - |f| - Optional. File be used as the program’s standard input. If CTLFILE is not specified, it is assumed that the data follows the RUN statement (up to, but not including, the next ENDRUN statement), and the those records are copied to a temporary file. If there are no data records following the RUN statement, CTLFILE is ignored.

  • MSG - |S| - Optional message that can be printed when the program runs. For readability, Bentley recommends 100 characters or less.

  • PARAMETERS - |SV| - Optional. Parameters that the program expects to find on the invoking command line. If a parameter will contain any special characters (comma, space, dash, math operator, semi-colon), enclose the parameter within quotes (‘…’ or “…”). If a parameter is to contain quotes, the quoted parameter must be enclosed by the opposite quote.

    For example, if the program requires ‘abc’ to be passed to it, it should be coded as "’abc’", or if it requires "def ghi", it should be coded as ‘"def ghi"’. Parameters may be coded as a series of values, or, in most cases, as one string of many parameters enclosed within one set of quotes.

  • PGM - |S| - Program to be run. Pilot determines if it is a CUBE Voyager program by searching for both "program.DLL" and "program.TDF" in the directories discovered in the following order:

    • Directory from which Pilot was loaded

    • Current directory

    • Windows system and then the Windows directories

    • Directories that are listed in the PATH environment variable

    If the program is not located that way, it assumes that it is a non-CUBE Voyager program and tries to locate it by applying a somewhat different set of criteria to determine the full name for the program, and to locate the directory where it resides.

    If program has no file extension and the last character is not a dot (.), append ".exe" to program.

    If program contains path information (has a or :), use that path

    If program does not contain path information, locate the program by searching the directory from which Pilot was loaded, and then the directories as registered with the operating system

    If program*.exe is found, look in that directory for the latest version of the program by assuming program#.exe and use the highest # file. Thus, if name.exe, name1.exe, and name3.exe are all found, name3.exe will be assumed.

  • PRNFILE - |F| - Optional. File where the program expects to write its standard system print output. PRNFILE will be ignored if it is determined that a TRIPS program is being run.

  • REDIRECTIN - |?| - Optional. Switch to indicate that CTLFILE is to be directed into the program.

  • REDIRECTOUT - |?| - Optional. Switch to indicate that the program is to direct its output to PRNFILE, if PRNFILE is also specified.

If it is determined that a TRIPS program is being run (by the presence of &FILES OPRN keyword in the CTLFILE), PRNFILE, REDIRECTIN, and REDIRECTOUT are ignored.

The RUN statement is designed to allow easy integration of non-CUBE Voyager programs directly in line with a standard run and to have the “printed” output of the program directly incorporated into the standard CUBE Voyager print file. There may be programs whose basic operations will not allow this type of integration. In those situations, it is possible that the use of the Pilot * statement will allow the direct running of the command.

The RUN statement for non-CUBE Voyager programs generates a system command that is structured and executed based upon the following decision table.

  • If PGM is a TRIPS program (contains &FILES OPRN=): 

    pgm ctlfile parameters >tprn

  • If PGM is not a TRIPS program:

    RDI RDO prnfile Generated command
    F F T pgm ctlfile prnfile parameters
    F F F pgm ctlfile parameters
    F T T pgm ctlfile parameters >prnfile
    F T F pgm ctlfile parameters >tprn
    T F T pgm prnfile parameters <ctlfile
    T F F pgm parameters <ctlfile
    T T T pgm parameters <ctlfile >prnfile
    T T F pgm parameters <ctlfile >tprn
    Note:

    1. If ctlfile has no length, it is not placed on the command line

    2. tprn is a temporary file which is copied to the CUBE Voyager print file.

    3. DRI/RDO = redirectin/redirectout

Examples 

RUN PGM=program parameters=datain, dataout
Command: Path\program.exe datain dataout
 
RUN PGM=abc.exe ctlfile=datain prnfile=dataout parameters=’abc’
Command: Path\abc.exe datain dataout abc
 
RUN PGM=ME ctlfile=datain parameters="/m=20" "/demo"
Command: Path\MVESTM70.EXE datain /m=20 /demo
 
RUN PGM=ME ; ctlfile follows this statement; will be copied to tfile 
Command: Path\MVESTM70.EXE tfile
 
RUN PGM="c:\util\pkzip.exe" parameters="junk.zip t*.", 
        "-v –c", prnfile=zip.txt, redirectout=t 
Command: c:\util\pkzip.exe junk.zip t*. -v –c >zip.txt
 
RUN PGM=MATRIX ; standard CUBE Voyager run

SENDMAIL

Immediately sends an e-mail.

Keywords include:

Use SENDMAIL to transmit the status of a job or job step to a recipient. The keywords SMTPSERVER, FROM, TO, and SUBJECT must be specified; the others are optional. E-mail messages can also be sent as text messages to a cell phone.

SENDMAIL keywords

  • ATTACHMENTS - |S| - List of file names sent as attachments. There is a maximum of 1000 attachments.

  • CC - |S| - E-mail address(es) for copied recipient(s).

  • FROM - |S| - E-mail address to be sent as the return.

  • MESSAGE - |S| - List of individual lines to send in the message area of the e-mail. Each string is a separate line. There is a maximum of 1000 messages.

  • PASSWORD - |S| - Password for the account specified in USERNAME, if the SMTP server requires secure logon.

    If coding your script in CUBE text editor, you can insert the password value with the Insert ribbon command then selecting Password for email. CUBE opens a Password Entry dialog box, which allows you to mask the password for security.

  • PORT - |I| - <25> is the TCP PORT number. The typical SMTP server uses PORT number 25.

  • SMTPSERVER - |S| - Name of the send-mail server. An example might be: smtp.sbcglobal.yahoo.com

  • SUBJECT - |S| - Subject of e-mail.

  • TO - |S| - E-mail address(es) of the recipient(s). Separate multiple recipient addresses with a comma. You can also send mail as a text message to a phone and account that supports text messaging.

    Examples of cell phone provider messaging e-mail addresses are:

    • T-Mobile: {phone#}@tmomail.net

    • Sprint: {phone#}@messaging.sprintpcs.com

    • Verizon: {phone#}@vtext.com

    Check with his/her cell phone service provider to verify the appropriate address.

  • USERNAME - User name for mail account, if the mail SMTP server requires logon.

Example

Using SENDMAIL with ONRUNERRORGOTO, RETURNCODE, and CLEARERROR to generate e-mail with attachments for various conditions

;======================================================================== 

ONRUNERRORGOTO='ONERROR' ; set LABEL to jump to if an error occurs
 
StepName='Step 1 - Network'
RUN PGM=NETWORK
NODEI=DTWNNOD.DBF, LINKI=DTWNLNK.DBF
NETO=DTWNTPP1.NET
ZONES=24
ENDRUN
 
StepName='Step 2 - Network'
RUN PGM=NETWORK
NODEI=xDTWNNOD.DBF, LINKI=DTWNLNK.DBF
NETO=DTWNTPP1.NET
ENDRUN
 
SENDMAIL SMTPSERVER='smtp.yourname.com',
FROM='ken@yourname.com',
TO='ken@yourname.com,jill@yourname.com',
CC='The Boss<boss@yourname.com>',
Subject='Email from Voyager, Run Completed, No Error',
Message='Voyager Run Completed',
'There is no run error',
ATTACHMENTS='DTWNTPP1.NET'
 
Exit ; if no errors then this step gets executed and terminates the run
 
:ONERROR ; if an error occurs the processing jumps to this location
 
rcode=str(returncode,2,0) ; returncode will have value=0,1,2,3
 
SENDMAIL SMTPSERVER='smtp.yourname.com',
FROM='ken@yourname.com',
TO='ken@yourname.com',
Subject='Email from Voyager, Run Error',
Message='There is a run error, returncode:',rcode,
'On Step ',StepName
 
; Also text message a cell phone
SENDMAIL SMTPSERVER='smtp.yourname.com',
FROM='ken@yourname.com',
TO='5106635200@messaging.sprintpcs.com',
Subject='Email from Voyager, Run Error',
Message='There is a run error, returncode:',rcode,
'On Step ',StepName
 
; If the error happens on step 2, ignore the error, resume the run
if (StepName='Step 2 - Network')
CLEARERROR resume=t code=0
endif

SLEEP

Pauses program execution for a specified amount of time.

Keywords include:

  • TIME - |RS| - Duration, in seconds, of the pause. Users can specify TIME as a constant numeric value or a variable. TIME does not accept an arbitrary expression.

Example 

SLEEP TIME = 5
 
; Pauses execution for five seconds
Parent topic: Pilot Program